HTMLFlashBox

The HTMLFlashBox function creates and displays a flash box without buttons. A flash box contains a message, title, and an optional icon, and is removed after a timeout or by the calling program.

Unlike the Platform SDK MessageBox function, the HTMLFlashBox function can display a check box to allow the user to prevent the flash box from displaying in the future. HTMLFlashBox supports displaying rich message text using simple HTML tagging described below.

int HTMLFlashBox(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  LPCTSTR messageText,             // pointer to text in flash box
  LPCTSTR titleText = 0,           // pointer to title of flash box
  UINT timeoutSeconds = 3,         // automatic timeout time
  UINT type = MB_ICONINFORMATION,  // style of flash box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  int iconResource = -1,           // icon resource ID
);

int HTMLFlashBox(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  UINT messageID,                  // the text string resource ID
  UINT titleID = 0,                // the title string resource ID
  UINT timeoutSeconds = 3,         // automatic timeout time
  UINT type = MB_ICONINFORMATION,  // style of flash box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  int iconResource = -1,           // icon resource ID
);

HWND HTMLFlashBoxModeless(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  LPCTSTR messageText,             // pointer to text in flash box
  LPCTSTR titleText = 0,           // pointer to title of flash box
  UINT type = MB_ICONINFORMATION,  // style of flash box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  UINT timeoutSeconds = -1,        // automatic timeout time
  int iconResource = -1,           // icon resource ID
);

HWND HTMLFlashBoxModeless(
  HWND hParent,                    // handle to the parent window (can omit if using MFC)
  UINT messageID,                  // the text string resource ID
  UINT titleID = 0,                // the title string resource ID
  UINT type = MB_ICONINFORMATION,  // style of flash box
  LPCTSTR displayInFutureText = 0, // pointer to display in future text
  UINT timeoutSeconds = -1,        // automatic timeout time
  int iconResource = -1,           // icon resource ID
);

Parameters

hParent

Handle to the parent window. This parameter can be omitted if using MFC.

messageText

Pointer to a null-terminated string containing the message to be displayed in the flash box. Note that you can use simple HTML tagging, as described below.

messageID

A resource ID for the string containing the message to be displayed in the flash box. Note that you can use simple HTML tagging, as described below.

titleText

Pointer to a null-terminated string containing the flash box title. If NULL or empty, the program name is used.

titleID

A resource ID for the string containing the flash box title. If NULL or empty, the program name is used.

displayInFutureText

Pointer to a null-terminated string containing the text for the Don't Display in Future check box. This check box is not displayed if the text is NULL or empty.

timeoutSeconds

The number of seconds to wait before the flash box times out, returning HTMLID_TIMEOUT.

iconResource

A resource ID for a custom flash box icon, or a value of 0 or less for no icon.

type

Icon Flag
Use one of the following flags to display an icon in the flash box. The icon flag is ignored if an icon resource ID is provided by the iconResource parameter.

Flag	Meaning
MB_ICONEXCLAMATION, MB_ICONWARNING	An exclamation-point icon appears in the flash box.
MB_ICONINFORMATION, MB_ICONASTERISK	An icon consisting of a lowercase letter i in a circle appears in the flash box.
MB_ICONQUESTION	A question-mark icon appears in the flash box.
MB_ICONSTOP, MB_ICONERROR, MB_ICONHAND	A stop-sign icon appears in the flash box.

Return Values

The return value is zero if there is not enough memory to create the flash box.

For the HTMLFlashBox function, the return value is HTMLID_TIMEOUT. For the HTMLFlashBoxModeless function, the return value is a pointer to the modeless dialog box (HWND), which must be destroyed by the calling program using DestroyWindow.

If a string provided for displayInFutureText and the user unchecks the box, HTMLID_DONTASKAGAIN is ORed in to the return value.

Description

For the HTMLFlashBox functions, you must supply a timeoutSeconds parameter greater than zero. Make the timeout long enough so that the user has a chance to view to the message. Timeouts between 3 and 5 seconds are effective for short messages.

The result of providing the displayInFutureText parameter is to display the text and have HTMLID_DONTASKAGAIN ORed in to the return value. The calling function is responsible for suppressing the flash box in the future.

You can set the font used by the message box functions using the HTMLSetFont function.

HTML Tagging

The message text may contain simple HTML tagging. HTML text is identified by starting with the <HTML> tag and ending with the </HTML> tag. Only the <HTML>, <H1>, <H2>, <H3>, <H4>, <P>, <B>, <I>, <CODE>, <BIG>, <SMALL>, and <BR> tags are supported. Newlines are not supported in HTML text, so you must use the <BR> tag to break lines. The < and > characters are supported to display the less than and greater than characters.

For the best results, use the HTML tagging with restraint.

Modeless Operation

When using the HTMLFlashBoxModeless functions, you can change the message text by calling GetDlgItem(HTMLID_MESSAGE_TEXT) and then SetWindowText. You can obtain the modeless return value by calling HTMLModelessReturnValue. You also need to provide a message loop so that the flash box can continue to receive messages and you should check to see if the user has finished with the flash box by calling HTMLModelessReturnValue within the message loop. A typical modeless flash box handler is as follows:


   HWND     hParent, hFlash;
   MSG      msg;
   int      retVal;

   // display the flash box
   hFlash = HTMLFlashBoxModeless(hParent, _T("<HTML>A <B>modeless</B> flash box.</HTML>"));

   // do processing
   while (DoSomeProcessing())
   {
      // check to see if the user has canceled
      if ((retVal = HTMLModelessReturnValue(hFlash)) >= 0)
         break;
      while (PeekMessage(&msg, 0, 0, 0, PM_REMOVE))
      {
         TranslateMessage(&msg);
         DispatchMessage(&msg);
      }
   }

   // get returned value (and do whatever you want with it)
   retVal = HTMLModelessReturnValue(hFlash);

   // destroy the modeless dialog
   DestroyWindow(hFlash);   // DestroyWindow deletes dialog

Note that if the user dismisses a modeless flash box, the window is hidden but not destroyed so the window handle is valid until you call DestroyWindow.

Sample Code

A typical flash box:


   #include "CtlHtml.h"

   HTMLFlashBox(hParent, _T("This is a flash box."), _T("3 Seconds"), 3, MB_ICONINFORMATION);

A typical flash box

A typical flash box with a Don't Display in Future check box (using MFC):


   HTMLFlashBox(_T("This is a flash box."), _T("5 Seconds"), 5, MB_ICONINFORMATION, 
     _T("Don't display this message in the future."));

A typical flash box with a Don't Display in Future check box

An HTML text flash box with the program name for the title (using MFC):


   HTMLFlashBox(_T("<HTML>This is an example of<BR><B>HTML text</B>.</HTML>"), 
     _T("5 Seconds"), 5, HTMLMB_CANCEL);

An HTML text flash box with the program name for the title